setup-steward: support single directory-symlink layout (Pattern D)#247
Merged
Conversation
Adds Pattern D to the adopter skills-dir conventions: one of `.claude/skills` / `.github/skills` is itself a directory symlink to the other, so both paths always reflect the same set of skills without per-skill plumbing. Two orientations: - **D.1** — canonical content under `.github/skills/`, `.claude/skills` is the symlink. Natural for projects that use `.github/` as their canonical infra-glue root (e.g. apache/airflow). - **D.2** — canonical content under `.claude/skills/`, `.github/skills` is the symlink. Natural for flat-Pattern-A projects that want a `.github/skills/` view too. Pattern D coexists with project-native skills and framework symlinks in the same canonical directory — the directory symlink fans them out automatically. Pre-Pattern-D consolidation: when both directories exist as regular directories with independent content (the would-be clobber-on-symlink case), the adopt flow surfaces the conflict and proposes a one-time consolidation — move every skill into one side, replace the other with a directory symlink — before wiring any framework symlink. Never auto-renames adopter content; falls back to Pattern A if the user declines. Updates to per-flow handling: - `conventions.md` — Pattern D section + two orientations, new detection-algorithm branches, table row, ambiguous-case rules, consolidation flow. - `adopt.md` — Step 0.4 calls into the consolidation flow when detection is ambiguous; Step 7 splits the `.gitignore` template per pattern (Pattern D only needs the canonical-side lines); Step 8 wires symlinks at the canonical side only for Pattern D. - `upgrade.md` — Step 4b adds a Pattern D branch (overwrite `setup-steward` at the canonical side; the directory symlink resolves the other side automatically); Step 6 refreshes only the canonical-side per-skill symlinks under Pattern D. - `verify.md` — Check 4 splits the required `.gitignore` entries per pattern. - `unadopt.md` — Inventory + execute-removal split per pattern; the directory symlink itself is adopter-owned and preserved. - `worktree-init.md` — Per-pattern layer count for the worktree's framework-skill symlinks. - `docs/setup/install-recipes.md`, `docs/setup/unadopt.md`, `SKILL.md` — same per-pattern guidance reflected in the contributor-facing docs.
This was referenced May 22, 2026
Merged
potiuk
added a commit
to apache/airflow
that referenced
this pull request
May 24, 2026
Backports the framework adoption from main (#66677 + #67149) so that v3-2-test gets the same agent-driven PR-management skills that main already uses, and so that future agentic fixes that ship as overrides under \`.apache-steward-overrides/\` cherry-pick cleanly to v3-2-test instead of hitting structural conflicts against the old self-hosted \`pr-triage\` skill. What changes: - Remove the self-hosted \`pr-triage\` skill at \`.github/skills/pr-triage/\` (and its symlink \`.claude/skills/pr-triage\`). Its functionality moves into the apache-steward framework as \`pr-management-triage\`, fetched on demand via the snapshot mechanism. - Wire up the apache-steward adoption: committed \`setup-steward\` bootstrap at \`.github/skills/setup-steward/\` (with a sibling \`.claude/skills/setup-steward\` symlink), \`.apache-steward.lock\` pinned to framework \`main\`, and the \`.apache-steward-overrides/\` directory with the three pr-management-triage config files (\`pr-management-config.md\`, \`pr-management-triage-ci-check-map.md\`, \`pr-management-triage-comment-templates.md\`) plus README and user.md. - Refresh the \`setup-steward\` bootstrap to the latest framework main (apache/magpie#247 — Pattern D single-directory-symlink layout) so adopters of the new framework benefit from the consolidated install flow. - Rewrite \`contributing-docs/25_maintainer_pr_triage.md\` to point at the framework skill URLs (\`apache/airflow-steward/.../pr-management-*\`) rather than the now-removed local skill paths. - Add the apache-steward section to \`AGENTS.md\` and the "Agent-assisted contribution" section to \`README.md\`. - Update \`.gitignore\` to allow-list \`setup-steward\` and to exclude the symlink families (\`security-*\`, \`pr-management-*\`, \`issue-*\`, \`setup-isolated-setup-*\`, \`setup-override-upstream\`, \`setup-shared-config-sync\`, \`list-steward-*\`) under both \`.claude/skills/\` and \`.github/skills/\`. - Update \`.pre-commit-config.yaml\` to skip \`.apache-steward-overrides/\` and \`.github/skills/setup-steward/\` in codespell and markdownlint (the framework prose uses hyphenated forms codespell flags as misspellings, and the snapshot-internal links break markdownlint). What does not change: - \`maintainer-review\` and \`pr-stats\` skills were never backported to v3-2-test, so there's nothing to remove for them — they will simply show up as \`pr-management-code-review\` and \`pr-management-stats\` after a fresh \`/setup-steward\`. - The \`lychee\` prek hook does not exist on v3-2-test, so its exclude hunk from main's adoption commit is N/A here. After this lands, contributors run \`/setup-steward\` in their agent harness to populate the gitignored \`.apache-steward/\` snapshot and make every \`pr-management-*\` skill invocable. See the README section "Agent-assisted contribution (apache-steward)" for the setup flow.
vatsrahul1001
pushed a commit
to apache/airflow
that referenced
this pull request
May 25, 2026
Backports the framework adoption from main (#66677 + #67149) so that v3-2-test gets the same agent-driven PR-management skills that main already uses, and so that future agentic fixes that ship as overrides under \`.apache-steward-overrides/\` cherry-pick cleanly to v3-2-test instead of hitting structural conflicts against the old self-hosted \`pr-triage\` skill. What changes: - Remove the self-hosted \`pr-triage\` skill at \`.github/skills/pr-triage/\` (and its symlink \`.claude/skills/pr-triage\`). Its functionality moves into the apache-steward framework as \`pr-management-triage\`, fetched on demand via the snapshot mechanism. - Wire up the apache-steward adoption: committed \`setup-steward\` bootstrap at \`.github/skills/setup-steward/\` (with a sibling \`.claude/skills/setup-steward\` symlink), \`.apache-steward.lock\` pinned to framework \`main\`, and the \`.apache-steward-overrides/\` directory with the three pr-management-triage config files (\`pr-management-config.md\`, \`pr-management-triage-ci-check-map.md\`, \`pr-management-triage-comment-templates.md\`) plus README and user.md. - Refresh the \`setup-steward\` bootstrap to the latest framework main (apache/magpie#247 — Pattern D single-directory-symlink layout) so adopters of the new framework benefit from the consolidated install flow. - Rewrite \`contributing-docs/25_maintainer_pr_triage.md\` to point at the framework skill URLs (\`apache/airflow-steward/.../pr-management-*\`) rather than the now-removed local skill paths. - Add the apache-steward section to \`AGENTS.md\` and the "Agent-assisted contribution" section to \`README.md\`. - Update \`.gitignore\` to allow-list \`setup-steward\` and to exclude the symlink families (\`security-*\`, \`pr-management-*\`, \`issue-*\`, \`setup-isolated-setup-*\`, \`setup-override-upstream\`, \`setup-shared-config-sync\`, \`list-steward-*\`) under both \`.claude/skills/\` and \`.github/skills/\`. - Update \`.pre-commit-config.yaml\` to skip \`.apache-steward-overrides/\` and \`.github/skills/setup-steward/\` in codespell and markdownlint (the framework prose uses hyphenated forms codespell flags as misspellings, and the snapshot-internal links break markdownlint). What does not change: - \`maintainer-review\` and \`pr-stats\` skills were never backported to v3-2-test, so there's nothing to remove for them — they will simply show up as \`pr-management-code-review\` and \`pr-management-stats\` after a fresh \`/setup-steward\`. - The \`lychee\` prek hook does not exist on v3-2-test, so its exclude hunk from main's adoption commit is N/A here. After this lands, contributors run \`/setup-steward\` in their agent harness to populate the gitignored \`.apache-steward/\` snapshot and make every \`pr-management-*\` skill invocable. See the README section "Agent-assisted contribution (apache-steward)" for the setup flow.
vatsrahul1001
pushed a commit
to apache/airflow
that referenced
this pull request
May 25, 2026
Backports the framework adoption from main (#66677 + #67149) so that v3-2-test gets the same agent-driven PR-management skills that main already uses, and so that future agentic fixes that ship as overrides under \`.apache-steward-overrides/\` cherry-pick cleanly to v3-2-test instead of hitting structural conflicts against the old self-hosted \`pr-triage\` skill. What changes: - Remove the self-hosted \`pr-triage\` skill at \`.github/skills/pr-triage/\` (and its symlink \`.claude/skills/pr-triage\`). Its functionality moves into the apache-steward framework as \`pr-management-triage\`, fetched on demand via the snapshot mechanism. - Wire up the apache-steward adoption: committed \`setup-steward\` bootstrap at \`.github/skills/setup-steward/\` (with a sibling \`.claude/skills/setup-steward\` symlink), \`.apache-steward.lock\` pinned to framework \`main\`, and the \`.apache-steward-overrides/\` directory with the three pr-management-triage config files (\`pr-management-config.md\`, \`pr-management-triage-ci-check-map.md\`, \`pr-management-triage-comment-templates.md\`) plus README and user.md. - Refresh the \`setup-steward\` bootstrap to the latest framework main (apache/magpie#247 — Pattern D single-directory-symlink layout) so adopters of the new framework benefit from the consolidated install flow. - Rewrite \`contributing-docs/25_maintainer_pr_triage.md\` to point at the framework skill URLs (\`apache/airflow-steward/.../pr-management-*\`) rather than the now-removed local skill paths. - Add the apache-steward section to \`AGENTS.md\` and the "Agent-assisted contribution" section to \`README.md\`. - Update \`.gitignore\` to allow-list \`setup-steward\` and to exclude the symlink families (\`security-*\`, \`pr-management-*\`, \`issue-*\`, \`setup-isolated-setup-*\`, \`setup-override-upstream\`, \`setup-shared-config-sync\`, \`list-steward-*\`) under both \`.claude/skills/\` and \`.github/skills/\`. - Update \`.pre-commit-config.yaml\` to skip \`.apache-steward-overrides/\` and \`.github/skills/setup-steward/\` in codespell and markdownlint (the framework prose uses hyphenated forms codespell flags as misspellings, and the snapshot-internal links break markdownlint). What does not change: - \`maintainer-review\` and \`pr-stats\` skills were never backported to v3-2-test, so there's nothing to remove for them — they will simply show up as \`pr-management-code-review\` and \`pr-management-stats\` after a fresh \`/setup-steward\`. - The \`lychee\` prek hook does not exist on v3-2-test, so its exclude hunk from main's adoption commit is N/A here. After this lands, contributors run \`/setup-steward\` in their agent harness to populate the gitignored \`.apache-steward/\` snapshot and make every \`pr-management-*\` skill invocable. See the README section "Agent-assisted contribution (apache-steward)" for the setup flow.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a fourth skills-dir convention — Pattern D, single
directory symlink — to the
setup-stewardadopter taxonomy:one of
.claude/skills/.github/skillsis itself a directorysymlink to the other, so both paths always reflect the same set
of skills without per-skill plumbing. Adding a new skill — project-
native or framework-installed — only needs one entry in the
canonical directory; the mirror is automatic.
Two orientations:
.github/skills/,.claude/skillsis the symlink. Natural for projects thatuse
.github/as their canonical infra-glue root (e.g.apache/airflow).
.claude/skills/,.github/skillsis the symlink. Natural for flat-Pattern-Aprojects that want a
.github/skills/view too withoutduplicating content.
Pattern D coexists with project-native skills and framework
symlinks in the same canonical directory — the directory symlink
fans them out across both paths automatically.
Pre-Pattern-D consolidation
When both
.claude/skills/and.github/skills/already existas regular directories with independent, non-aliased content,
applying Pattern D would clobber the side that becomes the
symlink. The adopt flow now surfaces the conflict and proposes
a one-time consolidation — move every skill into one side,
replace the other with a directory symlink — before wiring any
framework symlink. The framework never auto-renames adopter
content; if the user declines or unresolved name collisions
block consolidation, the flow falls back to Pattern A.
Files
.claude/skills/setup-steward/conventions.md— Pattern Dsection (both orientations), detection-algorithm branches,
table row, consolidation flow, ambiguous-case rules.
.claude/skills/setup-steward/adopt.md— Step 0.4 callsthe consolidation flow on ambiguous detection; Step 7 splits
the
.gitignoretemplate per pattern; Step 8 wiresframework symlinks at the canonical side only for D.
.claude/skills/setup-steward/upgrade.md— Step 4b adds aPattern D branch (overwrite
setup-stewardat the canonicalside); Step 6 refreshes per-skill symlinks at the canonical
side only.
.claude/skills/setup-steward/verify.md— Check 4 splitsthe required
.gitignoreentries per pattern..claude/skills/setup-steward/unadopt.md— Per-patterninventory + execute-removal; the directory symlink itself is
adopter-owned and preserved.
.claude/skills/setup-steward/worktree-init.md—Per-pattern layer count for worktree framework-skill symlinks.
.claude/skills/setup-steward/SKILL.md,docs/setup/install-recipes.md,docs/setup/unadopt.md—same per-pattern guidance reflected in the contributor-facing
docs.
Test plan
(apache/airflow), run `/setup-steward upgrade`, confirm
framework symlinks land at `.github/skills/` only and
every framework skill is reachable from
`.claude/skills/` via the directory symlink.
canonical-side ignore lines and the runtime framework
symlinks remain gitignored.
and a linked worktree; confirm all checks pass.
confirm the directory symlink itself is in the
preserved section.
🤖 Generated with Claude Code